Euroscene 1

home *** CD-ROM | disk | FTP | other *** search

/ Euroscene 1 / Euroscene 1.iso / resource / mac2e.lha / Mac2E / Docs / Mac2E.docE next >

Wrap

Text File | 1994-01-12 | 23.3 KB | 500 lines

******************************************************************************* Mac2E (v2.0) PreProcessor of macros for E language Archive of January the 9th 1994 (c) Copyright 1993, 1994, Lionel Vintenat ******************************************************************************* LOOK OUT ! Mac2E needs Workbench 2.0 or more to work. Sorry for 1.3 users (see `future'). Likewise, there are some restrictions for the using of the executa- ble files of this archive (see `bugs'). 1. Introduction ~~~~~~~~~~~~~~~ 1.1. How everything started... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At the beginning, there are the Amiga E and me. It was wonderful, together we made some nice programs in very little time. As I hadn't (and I still haven't yet) the RKMs, these programs were very ugly, without graphic interface, but no care, it was the good time... And then, MUI arrived, making relationship between Amiga E and me very difficult. Why ? Well, Amiga E doesn't allow to use macros, and to program MUI without macro, it's almost madness ! On the other hand, it was unthinkable to miss something like MUI. Then, I tried to use C language for some time : it was the beginning of dark years for my Amiga... And then, I had access to INTERNET. So I talked Wouter about my pro- blem, and he advised me to use a C preprocessor : what such a great idea ! But after several tries, it revealed very heavy to use : compilation time was multiplied by 100, and above all the compilator didn't print the corret number of line when an error occured. So the idea of Mac2E came... 1.2. Presentation ~~~~~~~~~~~~~~~~~ Mac2E is a preprocessor for the Amiga E compilator of Wouter van Oortmerssen, but which only knows one thing : to replace macros in E source files. In other words, the aspects "conditionnal compilation" and "file inclu- sion", for instance aren't supported by Mac2E, wheras it's the case in almost every C preprocessors. Why only this aspect ? See `how everything started...'. Ah ! I was forgetting : all the executable files of this archive are of course written in Amiga E ! 1.3. Spirit ~~~~~~~~~~~ I designed Mac2E following 3 ideas : - to make something simple to use (in the same way like Amiga E) - to resolve problems I met using a C preprocessor with Amiga E (see `how everything started...') - to make a preprocessor that using doesn't make E source files dependent of it, in other words, if the next version of Amiga E enables macro preprocessing (Wouter said to me it may be), changing from Mac2E to this preprocessor won't need a lot of modifications in your source files In that 2.0 version, I couldn't unfortunately success in making all that I wanted, namely that despite a lot of optimisations (see `history'), Mac2E isn't really fast (in truth very slow) relating to the rocket Amiga E. But don't be desesperate : I think that Mac2E is faster than a C preprocessor (I try with CPP, the C preprocesseur of GCC), and I will improve this in the next versions (see `future'). On the other hand : - Mac2E is closed to a C preprocessor in its using, so its learning will be very quick for the most part of programmers - Mac2E never introduce line feed when it replaces a macro, so the compilator always prints the correct line number in case of error - the definition of the macros is done in separated files different from your E source files, and the macro files are directly given to the Mac2E command without needing to change a character in your E source files, so changing from Mac2E to a future (maybe) Amiga E preprocessor will be very simple and won't oblige you to make a lot of modifications in your E source files So waiting the next release of Mac2E (see `future'), I advise all owners of slow Amiga to use, for big E source files with a lot of macros inside, the programme EPP of Barry Wills (e-mail bwillskkirk.safb.af.mil) available on aminet. This one allow to simulate file inclusion of a classic C preprocessor. So, you just have to concentrate the using of macros in one E source file (the remaining being distributed in another E source files) in order to use Mac2E only when you change this file full of macros, and not at any compilation. 2. Utilisation ~~~~~~~~~~~~~~ 2.1. Calling syntax ~~~~~~~~~~~~~~~~~~~ Mac2E is only a CLI command and can't be used from Workbench. Its calling syntax is very simple : Mac2E e_source_file e_destination_file {macro_files} where : - e_source_file is the name of a E source file (possibly with its path) which contains some macros to replace (see `macros in your source files') - e_destination_file is the name of a file (possibly with its path) which will be created by Mac2E, and which will contain e_source_file but with the macro replaced (see `macros in your source files') - {macro_files} is a list of names of macro files (possibly with their path), the names are seperated each other with some spaces (a least one) (see `macro files') For those who know, Mac2E parses the command line with the Workbench 2.0 function ReadArgs(). So the calling "Mac2E ?" returns the calling syntax "in ReadArgs form", namely "FROM/A,TO/A,WITH/A/M". So you can also call Mac2E in using the properties of the ReadArgs function. 2.2. Macro files ~~~~~~~~~~~~~~~~ Macro files are annex files, different from E source files, which contains only macro definitions. When you call Mac2E (see `calling syntax'), the macro files given as parameter are analysed to memorise the macros which are defined inside.They are these macros which will be used for the replace- ments in the E source file. 2.2.1. Structure ~~~~~~~~~~~~~~~~ The structure of a macro file is very simple. In fact, there's only 2 things to know. First, the definition syntax of a macro is exactly the same as in C language (see `macro definition'), particularly it begins with "#define". Second, between each macro definition, you can insert comments under the form you want (it isn't necessary to surround them with /* and */, or anything else). Indeed, Mac2E only searches the string "#define " in the macro file (avoiding all until it finds it) in order to point the beginning of a macro definition. So the only restriction for a comment is that it can't contain the string "#define ". 2.2.2. Macro definition ~~~~~~~~~~~~~~~~~~~~~~~ The macro definition must follow this syntax : #define macro1_name macro1_body or #define macro2_name(parameter1,parameter2) macro2_body or #define macro3_name macro3_body_part1 \ macro3_body_part2 \ macro3_body_part3 The first example corresponds to a very simple macro without any parameter, and which body fits one line. The second example corresponds to a macro with parameters. The third example corresponds to a macro which body doesn't fit one line. Once Mac2E has identified the macro, it begins again its blind search of the string "#define ". To understand how a macro is used, see `macros in your source files'. For more macro definition examples, see `Mac2E and MUI'. 2.2.2.1. #define ~~~~~~~~~~~~~~~~ So macro declaration begins by the string "#define". This one can be anywhere (not necessarily at the beginning of a line) and must always be followed by at least one space or one tabulation. If it isn't the case, Mac2E won't recognize the beginning of the macro declaration, and will go on without printing any error, so be careful ! 2.2.2.2. Macro names ~~~~~~~~~~~~~~~~~~~~ Then comes the name of the macro itself. This one can be any combina- tion of characters a..z, A..Z, 0..9 and _ (underscore). Namely, "120" or "__" or "FOR" are valid macro names, but I will never advise them to someone ! Don't be vicious, and rather call your macros "foo" or more seriously "Open_Window1". 2.2.2.3. Macro parameters ~~~~~~~~~~~~~~~~~~~~~~~~~ Then comes parameters declaration. A macro can have from 0 to an infi- nity of parameters. If it hasn't any, the macro body declaration replace para- meters declaration. But, if it gets some, they are separated each other by commas, and surrounded by parenthesises. The first of these ones must be sticked to the name of the macro. But you can insert some spaces or some tabu- lations among the commas, the parameter names, and the parenthesises inside these ones. The parameter names follow the same rules than the name of the macro itself. 2.2.2.4. Macro body ~~~~~~~~~~~~~~~~~~~ Finally, the macro declaration ends by the macro body. This one must be separated from the parameters (or from the macro name if the macro hasn't any parameter) by at least one space or one tabulation. In fact, all the spaces and all the tabulations that Mac2E meets before the body are eliminated. The first found character different from a space or from a tabulation indicates the body beginning. Now, all the met characters (even the spaces and the tabu- lations) are considered as part of the macro body. This one ends as soon as a carriage return is found. If the carriage return is preceded by a \, the carriage return and the \ are ingored and Mac2E continues to read following characters as part of the macro body. Be careful : the continuation of the 3 characters '\', ' ' and carriage return will be interpreted as if '\' and ' ' belong to the macro body and as if the carriage return indicates the end of the macro body. So, the carriage return must be sticked to the \ in order to make Mac2E understand that it must continue the reading of the macro body on the following line. The example below illustrate all this. Finding this macro definition #define macro body_part1 body_part2 \ body_part3 body_part4 \ \ body_part5 Mac2E will understand that macro has this body : "body_part1 body_patr2 body_part3 body_part4 \ body_part5" 2.3. Macros in your source files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After the analyse of all the macro files, Mac2E begins the replacing of macros in the source file given as parameter, and writes the destination file. 2.3.1. A macro in your source file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Mac2E identify a macro in the source file with its name (surprising isn't it ?). Be careful, Mac2E is case sensitive. To be identify, macro names must be preceded and followed by a separation character, namely different from a..z, A..Z and _. The contents of the comments (even if these ones are laced) or the strings between ' are avoided for the search. So you haven't to take care of conflicts that may appear. Likewise, the character ' in "'" isn't inter- preted as the beginning of a string. If it is possible to say that I have thought about all that may occur, I think that Mac2E can treat all the special cases like the previous one. But Mac2E assumes that your source file is correct. For instance, if you write 'rock'n roll' instead of 'rock\an roll' in one of your source files, Mac2E will interpret the second ' as the mark of the string end, and the third ' as the mark of the beginning of another string, that may cause some errors ! 2.3.2. A macro without any parameter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If Mac2E identify a macro foo in your source file, this macro being declared without any parameter, Mac2E will textually replace foo with its body. Of course, if this body itself contains some macro names, these ones will also be replaced in correct way. Be careful, Mac2E doesn't check if your macro definitions are recursive. So, if Mac2E seems to buckle and finally crashes, see again your macro definitions... 2.3.3. A macro with some parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let's take an example : Suppose that Mac2E indentify in your source file a macro foo which has been declared like that : #define foo(variable,value) variable:=variable+value Suppose now that in your source file, there is foo(a,3).Then Mac2E will textually replace foo(a,3) with a:=a+3. Namely, for each parameter you have given at declaration time (this kind of parameter is called formal parameter), Mac2E links a parameter you have given in your source file (this kind of parameter is called real parame- ter), and replace each occurence of a formal parameter by its linked real parameter in the macro body, before replacing the macro by its body itself. In order to work, the first parenthesis which introduces the real parameters must be directly sticked to the macro name. However, you can insert spaces or tabulations among the commas, the parameter names, and the parenthesis inside these ones. Of course, if the body itself contains some macro names, these ones will also be replaced in correct way. Be careful, Mac2E doesn't check if your macro definitions are recursive. So, if Mac2E seems to buckle and finally crashes, see again your macro definitions... But, you can write in your source files foo1(foo2(foo3)) where foo1, foo2 and foo3 are macros, Mac2E will replace all that correctly. 2.4. Errors ~~~~~~~~~~~ For in/out errors (impossible to open the source file for instance), Mac2E print a fully explaining message. But for errors met during macro file analyse or during source file analyse, Mac2E only prints a very simple message which looks like "Error in line 100 !", always for speed considerations. The returned line number is exact at about 1. Indeed, the printed error may be at the previous line. During macro file analyse, Mac2E only prints an error if the defini- tion syntax of one of your macro is faulty. See `macro definition'. During source file analyse, Mac2E only prints an error if a macro has been identified but the number of its arguments is wrong. 3. Mac2E and MUI ~~~~~~~~~~~~~~~~ If you have read `how everything started...', you know that Mac2E exists because MUI is infinitively easier to program with macros than without. So the first (and the only one for now) using example of Mac2E is related with MUI. You can find in this archive all that you need to use MUI with Amiga E, in the same way as in C language. To do this, you need 5 things : - Mac2E : see `presentation' and `utilisation' - mui.m - muimaster.m - mui.e - OptiMUI2E I remind you that designing mui.m and mui.e, I wanted to do a "MUI-Amiga E interface" very closed to the C one, so during programing, I advise you to have next to your Amiga the listing of the mui.h file. Indeed, this file contains a lot of comments I erased in mui.e to speed up analyse. All this "interface" is based on MUI 1.4. In the MUI archive, there are yet some files to use MUI with E language, but they aren't and by far as much powerful as those provided in this archive. So forget them and use mine ! 3.1. mui.m ~~~~~~~~~~ mui.m is (as its name indicates it) a classical E include file. It contains all the structures defined in mui.h, with the only difference that all the names (structure names and field names) are in tiny letters. This limitation is Iconvert fault. Indeed, I use an asm include file where I define all the mui.h structures in assembling macros, and with the original name (keeping case sensitivity) to create mui.m. But unfortunately, Iconcert, which translate this asm include file in an E include file, makes all the names being writen with tiny letters. So, if you want to use MUI structures, you have to put at the beginning of your source file MODULE 'libraries/mui.m'. 3.2. muimaster.m ~~~~~~~~~~~~~~~~ muimaster.m is (as its name indicates it) a classical E include file. It contains all the function definitions of the muuimaster library. The func- tion names are the same than in C language with the only difference that they begin with MuI instead of MUI (example : MuI_NewObjectA). This limitation is enforced by Amiga E, because function names must have their first letter capital and the second tiny. So, if you want to use MUI functions, you have to put at the beginning of your source file MODULE 'muimaster.m'. 3.3. mui.e ~~~~~~~~~~ mui.e is the real force of this "MUI-Amiga E interface" because it contains all the mui.h macros (constants and more complicated things like object definitions), but designed to be used with Amiga E. The syntax of the mui.e macros (declaration and body) is exactly the same than in mui.h file. So, if you want to use these MUI macros in your E source files, you have to launch Mac2E on them before calling the compilator : Mac2E source.e destination.e MacroFiles/mui.e 3.4. OptiMUI2E ~~~~~~~~~~~~~~ If you look at `mui.e', you will see inside the body of object defin- ition macros some "TAG_IGNORE,0", for instance "#define WindowObject MuI_NewObjectA('Window.mui',TAG_IGNORE,0". This tag (as its name indicates it) doesn't make anything at execution time. However, I was obliged to introduce some to keep the same syntax as in C language because E lists must be surrounded by [ and ]. So OptiMUI2E comes. This program removes these useless "TAG_IGNORE,0" from your E source files. Its calling syntax is : OptiMUI2E e_source_file e_destination_file where - e_source_file is the name of a source file (eventually with its path) written in E language where there are some "TAG_IGNORE,0" - e_destination_file is the name of a file (eventually with its path) which will contain e_source_file with all the "TAG_IGNORE,0" removed OptiMUI2E also uses the ReadArgs() function of Workbench 2.0 to parse its command line. The input format of OptiMUI2E is "FROM/A,TO/A". In fact, OptiMUI2E replace the string "[TAG_IGNORE,0," (typical of a MUI macro which creates an object) by [. Be careful, OptiMUI2E sometimes removes carriage return from your source files to respect E syntax where lines must end on a comma. So, it's not sure that the destination file has the same number of lines than the source one, which may cause the compilator give wrong line number in case of error. So, I advise you to use OptiMUI2E only for a final compilation when your program is finished and fully tested. Anyway, OptiMUI2E isn't necessary at all to use MUI with Amiga E. It reduces a bit the source file size and the executable file size when they use MUI macros, but it isn't Power Packer ! I only make OptiMUI2E because I'm maniac, and I think that only those who are maniac too will use OptiMUI2E ! Be careful (bis), OptiMUI2E doesn't work on 68000 based Amiga (see `bugs'). 4. Bugs ~~~~~~~ Don't panic ! The list below doesn't contain only bugs, but rather some restrictions. * Mac2E only works under Workbench 2.0 or more : the next version will run under 1.3 (see `future') * OptiMUI2E doesn't work on 68000 based Amiga. As mine has a 68030 inside, I didn't take care of even address alignement, et it was too late when I realized my error... Anyway, this program isn't necessary at all, and I think I will correct this in the next version (see `future') * Mac2E doesn't check if your macro declarations are recursive, so if it is the case, Mac2E may go in very deep thoughts that only a reset will be able to stop... * Mac2E doesn't always check that it gets all the memory it requested. For big memory requests (like for loading a file), it checks that it has got what it had requested, but not for small memory requests (like 10 bytes to store a macro name), always for speed considerations. So, never launch Mac2E during critical memory conditions, where it may crash your Amiga... However, this wouldn't be a big problem because Mac2E isn't really memory hungry : it needs about the total of all used macro file sizes added to the source file size, and added to about 10 Ko (to be sure). * Mac2E doesn't exactly check the validity of your macro definitions explained in `macro definition'. Some more laxist definitions may be accepted by Mac2E. However, I won't tell you which ones, so nobody will try them. It's better to follow this previous advice because the next versions of Mac2E will be less tolerant. To sum up, all the executable files of this archive are full of bugs, but they may run without any problem in 99% of cases, and with good results. I prefered sacrify the robustness of these programs than their speed. 5. History ~~~~~~~~~~ * v1.0 : first working version of Mac2E (VERY VERY SLOW...) * v2.0 : version identical to the 1.0 one, but with a lot of assembling opti- misations (10 times faster !) Opti2MUI added first released version 6. Future ~~~~~~~~~ This first released version of Mac2E is completly working but compared to AmigaE it's a tortoise ! So, for the next versions, I will try to improve the speed : - all macro files will be pre-processed to speed up their analyse - Mac2E will allow file inclusion in the same way like a C preprocessor by calling itself Amiga E and by managing itself the line numbers in case of error by using the compiler messages - Mac2E will manage macro preprocessing a bit like the tool "make", in order to do macro replacings only when it's necessary - Mac2E will be able to directly call OptiMUI2E - Mac2E will run under Workbench 1.3 - I will probably change Mac2E name if all previously features are supported ! - OptiMUI2E will be proposed in 68000 and 68020+ versions This can seem a bit ambitious, but the base is still there. So, if not too much bugs are reported (I hope so !), it may not take a long time to do. Wait and see ! 7. Distribution ~~~~~~~~~~~~~~~ You can freely redistribute this archive by any way of communication. This archive can also be put in any public domain collection like FISH, CAM or DPAT. But nothing except the price of disks and the price of the sending can be asked for redistribution. However, the WHOLE archive must be redistri- bute. It must have the following structure : Mac2E/Bin/Mac2E Mac2E/Bin/OptiMUI2E Mac2E/Docs/Mac2E.docE Mac2E/Docs/Mac2E.docF Mac2E/Docs/Mac2E.guideE Mac2E/Docs/Mac2E.guideF Mac2E/MacroFiles/mui.e Mac2E/Modules/libraries/mui.m Mac2E/Modules/muimaster.m Mac2E/readme.first Mac2E/ReadMe.mui Likewise, all these files (except mui.m, muimaster.m, mui.e and ReadMe.mui) stay under copyright of `the author'. None of them can be modi- fied without my authorization. This program is provided without any warranty of any kind : you use it at your own risk ! This program is distributed under the concept of Freeware, so you aren't obliged at all to send me something ! But, I will be happy to receive anything : Amiga 4000/40, post card, 5$ or a simple e-mail... 8. The author ~~~~~~~~~~~~~ You can contact me by mail : - at my student address until July 1994 included Lionel Vintenat appartement 21 11 rue François Oulié 31500 TOULOUSE FRANCE - at my family address Lionel Vintenat 3 impasse Boileau Lotissement Les Termes 87270 COUZEIX FRANCE I'd rather receive mail at my student address until July 1994 because I'm there almost all the time. You can also contact me through INTERNET. My e-mail address is vintenat@irit.fr. I'd rather by far receive e-mail than postal mail. I will always answer questions which will be asked me by e-mail, but on the other hand, don't expect any answer to postal mail (I become very lazy each time I have to take a pen...) 9. Credits ~~~~~~~~~~ Sepcial thanks : - to the Amiga to be the best personal computer - to Wouter van Oortmerssen for all his work in compilation domain (try FALSE, I promise you a surprise !) in general and especially for Amiga E - to Eric Totel to press me to finish this documentation in a reasonable delay - to Stephan Sürken (e-mail s_suerke@informatik.uni-kl.de) for his Text2Guide utility that I used to make hypertext documentations of this archive - to every member of the French Amiga mailing list who had helped me - to every programmer who makes public domain in general Finally, more thanks to all those who will report `bugs', or who will make some suggestions, or who will send me corrections or translations of this documentation (excuse me for the very bad English...) Good programming time with Amiga E and... NEVER FORGET, ONLY AMIGA MAKES IT POSSIBLE !